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Description 


Added the following mandatory fields: 
e CustName 

e CustEmail 

e CustPhone 


Added the following non-mandatory field: 
e CustMAC 


Modified the following conditional field to be 
mandatory: 
e CustlP 


Added Reversal Pending status (31) in section 3.3 
(Query Transaction Status) 


Added MerchantApprovalURL and 
MerchantUnApprovalURL in section 2.1 (Payment 
Request) 


Added MerchantApprovalURL and 
MerchantUnApprovalURL іп section 2.7.1.1 
(Payment Request Hashing) 


Added SessionID їп section 2.1 (Payment 
Request) 


Added TokenType and Token in section 2.1 
(Payment Request) and section 2.2 (Payment 
Response) 


Added MerchantCallBackURL in section 2.1 
(Payment Request) and section 2.7.1.1 (Payment 
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Added B4TaxAmt and TaxAmt in section 2.1 
(Payment Request) 


Added transaction type AUTH in TransactionType 
field of section 2.1 (Payment Request) 


Added transaction type CAPTURE in section 2.5 
(Capture Request) 
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Added Param6 and Param7 in section 2.1 
(Payment Request) and section 2.2 (Payment 
Response) 


Added AUTH and CAPTURE in section 3.1 
(Transaction Type) 


Added status 15 for Auth, 16 for Captured in 


section 3.3 (Query Transaction Status) 


Added transaction type REFUND in section 2.9 
(Refund Request) 


Added status 10 for Refunded in section 3.3 
(Query Transaction Status) 
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1 Introduction 


Payment Gateway provides a web interface that allows integration with Merchant System which 
would like to accept online payment by 3D and non-3D credit card, direct debit and e-Wallet 
payments. 


This Merchant Integration Guide provides merchants with the necessary technical information to 
integrate their applications (Merchant Systems) with Payment Gateway. 


The manual contains message format required between Payment Gateway and Merchant System 
for various payment transaction types, namely Payment, Query and Reversal. It is intended as a 
technical guide for merchant developers and system integrators who are responsible for designing 
or programming the respective online applications to integrate with Payment Gateway. 


1.4  Pre-requisite 


All merchants who would like to integrate with Payment Gateway must obtain a valid payment 
account from eGHL. Upon payment account generated, eGHL will provide merchant a Service ID 
and Merchant Password. 
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Payment API Reference Fields (HTTP GET and POST) 


Payment Request (Merchant System — Payment Gateway) 


The following fields are the Payment information expected from Merchant System to Payment 
Gateway in order to perform an online payment transaction: 


No. 


Field 


Data 
Type 


Max 
Length 


Req? 


Description 


TransactionType 


SALE - Direct captured for credit card 
payment; Payment request for other 
payment methods 


AUTH - For credit card payment, 
authorize the availability of funds for a 
transaction but delay the capture of funds 
until a later time. This is often useful for 
merchants who have a delayed order 
fulfillment process. Authorize & Capture 
also enables merchants to modify the 
original authorization amount due to 
order changes occurring after the initial 
order is placed, such as taxes, shipping 
or item availability 


Re: Section 2.5 for Transaction Type 
CAPTURE message format 


PymtMethod 


Payment Method 


CC - Credit Card 

DD - Direct Debit (not applicable to 
TransactionType AUTH) 

WA - e-Wallet (not applicable to 
Transaction Type AUTH) 

ANY — All payment method(s) registered 
with eGHL 


ServicelD 


AN 


Merchant Service ID given by eGHL 


PaymentlD 


AN 


20 


Unique transaction ID/reference code 
assigned by merchant for this payment 
transaction 


(No duplicate PaymentID is allowed) 


OrderNumber 


AN 


20 


Reference number / Invoice number for 
this order 

PaymentID must be unique but 
OrderNumber can be the same under 
different PaymentlD, indicating multiple 
payment attempts are made on a 
particular order 
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If Order Number is not applicable, please 
provide the same value as PaymentID 


6. PaymentDesc AN 100 Y Order's descriptions 


Merchant system's browser redirect 
URL which receives payment response 
from eGHL when transaction is 
completed (approved/declined/system 


error/ 
cancelled by buyer on eGHL Payment 
Page) 

7. | MerchantReturnURL AN 255 Y If MerchantApprovalURL is provided, 
when payment is approved, 


MerchantApprovalURL will be used 
instead of MerchantReturnURL 


If MerchantUnApprovalURL is provided, 
when payment is declined, 
MerchantUnApprovalURL will be used 
instead of MerchantReturnURL 


Payment amount in 2 decimal places 
regardless whether the currency has 
decimal places or not. 


Bo cS АПИ N 12(2) Y Please exclude “,” sign. 
e.g. 1000.00 for IDR 
Invalid format: 1,000.00 or 1000 
3-letter 1504217 of Payment Currency 
9. | CurrencyCode A 3 Y Goda 
Re: Section 3.5 
Message digest value calculated by 
Merchant System in hexadecimal string 
10. | HashValue AN 100 Y using SHA256 hash algorithm 
Re: Section 2.7.1.1 
11. | CustIP AN 20 y Customers |P address captured by 
merchant system 
12. | CustName AN 50 Y Customer Name 
13. | CustEmail AN 60 Y Customer's Email Address 
14. | CustPhone AN 25 Y Customer's Contact Number 
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15. 


B4TaxAmt 


12(2) 


Original amount before tax is incurred, in 
2 decimal places regardless whether the 
currency has decimal places or not. 


As for final payment amount after tax is 
incurred, is to be specified in Amount 
field 


из» 


Please exclude “,” sign. 


e.g. 1000.00 for IDR 
Invalid format: 1,000.00 or 1000 


16. 


TaxAmt 


12(2) 


Tax amount incurred 


“oy 


Please exclude “,” sign. 


e.g. 1000.00 for IDR 
Invalid format: 1,000.00 or 1000 


17. 


MerchantName 


AN 


25 


Merchant's business name 


18. 


CustMAC 


AN 


50 


Machine ID (МАС Address) of 
customer's computer/device which was 
used to make payment 


19. 


MerchantApprovalURL 


AN 


255 


URL to link to merchant's website when 
payment is approved 


If not provided, MerchantReturnURL will 
be used 


20. 


MerchantUnApprovalURL 


AN 


255 


URL to link to merchant's website when 
payment is declined 


If not provided, MerchantReturnURL will 
be used 


21. 


MerchantCallBackURL 


AN 


255 


Server-to-server URL as an additional 
link to merchant's website to be informed 
of transaction status 


This is useful when browser redirect 
URLs 
(MerchantReturnURL/MerchantApproval 
URL/MerchantUnApprovalURL) were not 
able to receive payment response due to 
buyer's Internet connectivity problem or 
buyer closed browser 
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Upon receiving response from Gateway, 
MerchantCallBackURL is to return an 
acknowledgement message "OK" to the 
Gateway or else Gateway will continue to 
send response to this URL for a 
maximum of 3 times 


22. 


LanguageCode 


Language Code for eGHL Payment Info 
Collection Page 


Re: Section 3.6 


23. 


PageTimeout 


eGHL Payment Info Collection Page 
timeout in seconds 


Applicable for merchant system which 
would like to bring forward to Payment 
Gateway, the time remaining before 
product/order is released 


For example, a movie ticket sales page 
shows time remaining countdown from 
15 minutes till 5 minutes. Upon 
customer’s clicking “checkout / proceed / 
pay” button, merchant system can then 
pass the value of (5 minutes x 60 
seconds=300) seconds in this field to 
Gateway which will then continue the 
countdown from 5 minutes. Upon 
timeout, all entry fields and buttons on 
the Collection Page will be disabled 


24. 


CardHolder 


AN 


30 


Cardholder's Name 


For PymtMethod “СС”, if not provided, 
Payment Gateway will prompt this field 
on eGHL Payment Info Collection Page 


25. 


CardNo 


Credit Card Number used for payment 
authorization 


For PymtMethod “СС”, if not provided, 
Payment Gateway will prompt this field 
on eGHL Payment Info Collection Page 


If merchant has own payment page to 
collect card information, merchant 
system is required to be PCI compliant 


26. 


CardExp 


Expiry date of credit card. Date format is 
YYYYMM, e.g. 201312 for year 2013 
December 
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For PymtMethod “СС”, if not provided, 
Payment Gateway will prompt this field 
on eGHL Payment Info Collection Page 


27. 


CardCVV2 


3-4 digits Card Verification Value 
available on the back of credit card 


For PymtMethod “СС”, if not provided, 
Payment Gateway will prompt this field 
on eGHL Payment Info Collection Page 


28. 


IssuingBank 


AN 


30 


For PymtMethod “СС”, this field indicates 
Bank which issued the credit card used 
for this transaction 


If not provided, Payment Gateway will 
prompt this field on eGHL Payment Info 
Collection Page 


For PymtMethod “ОР”, this field indicates 
Direct Debit banks/payment switches. 


If not provided, the list of Direct 
Debit/payment switches supported will be 
shown on eGHL Payment Info Collection 
Page 


29. 


BillAddr 


AN 


100 


Billing Address (excludes postcode, 
town/city, state and country) 


For PymtMethod “СС”, if not provided, 
Payment Gateway will prompt this field 
on eGHL Payment Info Collection Page 


30. 


BillPostal 


AN 


Billing Postcode 


For PymtMethod “СС”, if not provided, 
Payment Gateway will prompt this field 
on eGHL Payment Info Collection Page 


31. 


BillCity 


30 


Billing Town/City 


For PymtMethod “СС”, if not provided, 
Payment Gateway will prompt this field 
on eGHL Payment Info Collection Page 


32. 


BillRegion 


30 


Billing Region/State 


For PymtMethod “СС”, if not provided, 
Payment Gateway will prompt this field 
on eGHL Payment Info Collection Page 
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Billing Country Code 


Re: Section 3.7 


33. | BillCountry A 2 
For PymtMethod “СС”, if not provided, 
Payment Gateway will prompt this field 
on eGHL Payment Info Collection Page 
34. | ShipAddr AN 100 Shipping Address (excludes postcode, 
town/city, state and country) 
35. | ShipPostal AN 15 Shipping Postcode 
36. | ShipCity A 30 Shipping Town/City 
37. | ShipRegion A 30 Shipping Region/State 
Shipping Country Code 
38. | ShipCountry A 2 
Re: Section 3.7 
39. | SessionID AN 100 Session ID 
Token Type 
40. | TokenType A 3 
OCP - One-click Payment 
Token Value 
"ORT Token ANS 2n If TokenType is specified, Token is 
expected to have value 
Additional data from merchant system 
42. | Param6 ANS 50 that will be passed back to merchant in 
payment response 
Additional data from merchant system 
43. | Param7 ANS 50 that will be passed back to merchant in 


payment response 


Req? — Required? (Mandatory fields?) 


Y — Yes 


N- No 


C - Conditional 
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Sample HTML Form Post Payment Request 


«form name="frmPayment" method="post" action="https://xxx.e- 
ghl.com/IPG/payment.aspx"> 

<input type="hidden" name="TransactionType" value="SALE"> 

<input type="hidden" name="PymtMethod" value="CC"> 

<input type="hidden" name="ServiceID" value="A@7"> 

<input type="hidden" name="PaymentID" value="ABCDEFGH130820142128"> 
<input type="hidden" name="OrderNumber" value="IJKLMN"> 

<input type="hidden" name="PaymentDesc" value="Booking No: IJKLMN, Sector: 
KUL-BKI, First Flight Date: 26 Sep 2012"> 

<input type="hidden" name="MerchantName" value="Merchant А" > 

<input type="hidden" name="MerchantReturnURL" 
value="https://merchA.merchdomain.com/pymtresp.aspx"> 

<input type="hidden" name="Amount" value="228.00"> 

<input type="hidden" name="CurrencyCode" value="MYR"> 

<input type="hidden" name="CustIP" value="192.168.2.35"> 

<input type="hidden" name="CustName" value="Jason"> 

<input type="hidden" name-"CustEmail" value="Jason@gmail.com"> 
<input type="hidden" name="CustPhone" value-"60126902328"» 

<input type="hidden" name="HashValue" value="hash value generated" > 
<input type="hidden" namez"MerchantTermsURL" 
value-z"http://merchA.merchdomain.com/terms.html"» 

<input type="hidden" name-"LanguageCode" value="en"> 

<input type="hidden" name-"PageTimeout" value-"780"» 

</form> 
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Payment Response (Payment Gateway — Merchant System) 


Upon payment process completion, the following fields will be returned from Payment Gateway to 
Merchant System's MerchantReturnURL in order to complete an end-to-end payment process: 


5 Data Max ani 
9 
No. Field Type | Length Req? Description 
1. | TransactionType A 7 Y Follows request 
Payment Method 
2. | PymtMethod A 3 Y CC - Credit Card 
DD - Direct Debit 
WA - e-Wallet 
3. ServicelD AN 3 Y Follows request 
4. PaymentID AN 20 Y Follows request 
5. OrderNumber AN 20 Y Follows request 
6. | Amount N 12(2) Y Follows request 
7. | CurrencyCode N 3 Y Follows request 
Message digest value calculated by 
Payment Gateway in hexadecimal string 
8. | HashValue AN 100 Y using SHA256 hash algorithm 
Re: Section 2.11.1.2 
Unique Transaction ID or Reference 
9. | TxnID AN 30 Y Code assigned by Payment Gateway for 
this transaction 
Follows request if this field is provided in 
request 
If not provided in request, 
For PymtMethod “СС”, this field is the 
10. | IssuingBank AN 30 Y Bank Name keyed in by customer on 


eGHL Payment Info Collection Page 


For PymtMethod “DD”, this field is the 
Bank Name chosen by customer to 
perform Direct Debit transaction 
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11. | TxnStatus N 4 Re: Section 3.2 

12. | AuthCode AN 12 Authorization Code returned by bank 

18. | TxnMessage AN 255 Message that briefly explains the 
response 
Token Type 
If merchant is subscribed to eGHL One- 

14. | Teen Type А 3 Click Payment feature, upon payment 
approved, TokenType will be "OCP", 
together with token value in Token field 
Token Value 

15. | Token ANS 50 If Token Type is "OCP", Token field will 
hold the Token Value for One-Click 
Payment purposes 

16. | Param6 ANS 50 C Follows request 

17. | Param7 ANS 50 C Follows request 


Sample VB.net Code to Retrieve Payment Response Fields 


Imports System.Web 


Vari = Server.UrlDecode(HttpContext.Current.Request(*PaymentID") 
Var2 = Server.UrlDecode(HttpContext.Current.Request(“OrderNumber” ) 
Var3 = Server.UrlDecode(HttpContext.Current.Request(* Amount") 

Var4 = Server.UrlDecode(HttpContext.Current.Request(*CurrencyCode") 
Var5 = Server.UrlDecode(HttpContext.Current.Request(*TxnID") 

Var6 = Server.UrlDecode(HttpContext.Current.Request(*PymtMethod") 
Var7 = Server.UrlDecode(HttpContext.Current.Request(*TxnStatus") 
Var8 = Server.UrlDecode(HttpContext.Current. Request (“AuthCode”) 
Var9 = Server.UrlDecode(HttpContext.Current.Request(*TxnMessage") 
Маг10 = Server.UrlDecode(HttpContext.Current.Request(*IssuingBank") 
Var11 = Server.UrlDecode(HttpContext.Current.Request(*HashValue") 
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Query Request (Merchant System — Payment Gateway) 


The following fields are the Payment information expected from Merchant System to Payment 


Gateway in order to query payment status. 


No MerchantReturnURL involved. Merchant System can get query response on the same 


session. 
A Data Max ЕА 
9 

No. Field Type | Length Req? Description 

1. | TransactionType A 7 Y QUERY 
Payment Method submitted in the original 

z рад 2 a К Payment Request being queried 

3. | ServicelD AN 3 Y Merchant Service ID given by eGHL 
Unique Transaction ID or Reference 

4. PaymentlD AN 20 Y Code assigned by Merchant System for 
the original Payment Request being 
queried 

& | Amount N 12(2) Y Payment Amount submitted in Payment 
Request 

6. | CurrencyCode А 3 Y Payment Currency Code submitted in 
Payment Request 
Message digest value calculated by 
Merchant System in hexadecimal string 

7. | HashValue AN 100 Y using SHA256 hash algorithm 
Re: 2.7.1.3 
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Sample VB.net Code HTTP POST Query Request And Receive Query Response 
Reference: http://msdn.microsoft.com/en-us/library/debx8sh9.aspx 


Imports System 
Imports System.IO 
Imports System.Net 
Imports System.Text 
Namespace Examples.System.Net 
Public Class WebRequestPostExample 


Public Shared Sub Main() 
' Create a request using a URL that can receive a post. 
Dim request As WebRequest - WebRequest.Create("https://secure2pay.e- 
ghl.com/IPG/payment.aspx ") 
' Set the Method property of the request to POST. 
request.Method - "POST" 
' Create POST data and convert it to a byte array. 


Dim postData As String - 
"TransactionType-QUERY&PymtMethod-zCC&ServiceID-A07&PaymentID- 
ABCDEFGH130820142128&Amount-228.00&CurrencyCode-MYR&HashValue-hash value generated" 


Dim byteArray As Byte() - Encoding.UTF8.GetBytes(postData) 
' Set the ContentType property of the WebRequest. 
request.ContentType = "application/x-www-form-urlencoded" 
' Set the ContentLength property of the WebRequest. 
request.ContentLength - byteArray.Length 

' Get the request stream. 

Dim dataStream As Stream - request.GetRequestStream() 

' Write the data to the request stream. 
dataStream.Write(byteArray, 0, byteArray.Length) 

' Close the Stream object. 

dataStream.Close() 

' Get the response. 

Dim response As WebResponse - request.GetResponse() 

' Display the status. 

Console.WriteLine(CType(response, HttpWebResponse).StatusDescription) 
' Get the stream containing content returned by the server. 
dataStream - response.GetResponseStream() 

' Open the stream using a StreamReader for easy access. 

Dim reader As New StreamReader(dataStream) 

' Read the content. 

Dim responseFromServer As String - reader.ReadToEnd() 

' Display the content. 

Console.WriteLine(responseFromServer) 


' +++++ Parse Query Response Here +++++++++++++++++++++++++++++++++++++ 

' +++++ Sample of Query Response Is Available On The Next Section +++++ 

' Clean up the streams. 
reader.Close() 
dataStream.Close() 
response.Close() 

End Sub 
End Class 
End Namespace 
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2.4 Query Response (Payment Gateway — Merchant System) 


Upon query process completion, Payment Gateway will return all fields same as Payment 
Response fields together with the following additional fields. 


For Query transaction status, please refer to section 3.3. 


No MerchantReturnURL involved. Merchant System can get query response on the same 
session. 


No. Field did vue Req? Description 
An identifier to indicate whether the 
transaction being queried exists in 
Payment Gateway. 
0- 
Transaction being queried exists in 
Payment Gateway. Merchant System can 
proceed to refer to the rest of other fields 
for details, e.g. TxnStatus 
1- 
Transaction being queried does not 
14. | TxnExists N 1 Y exist in Payment Gateway. In other 
words, Payment Gateway is not able to 
find any transaction that is matched with 
all Query request fields submitted by 
merchant system 
TxnStatus will be -1 
2 – 
There was some kind of internal error 
occurred during query processing. 
Merchant System can retry sending 
query request 
TxnStatus will be -2 
15. | QueryDesc AN 255 N Description of query result 
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Sample Query Response (A single string will be returned to Merchant System on the same 
Query session) 


TxnExists-0&QueryDesc-Exists&ServicelDzD01&PymtlD-ABC1234567890&Amount-1234.00& 
CurrencyCode-THB&TxnStatus-0&......... 


Sample Query Response (TxnExistsz1) 
TxnExists=1&QueryDesc=Transaction Not 
Exists& TransactionT ype=QUERY&PymtMethod=CC&ServicelD=TIS&PaymentID=JEFSIT 131107 
00004&OrderNumber=&Amount=0.14&CurrencyCode=MYR&TxnID=&lssuingBank=&T xnStatus= 


1&AuthCode-&BankRefNo-&TxnMessage-&HashValue-1d54f8eb9ff6c92c09737f6108a68afed0 
ff1725a5c22efbc3b7cb5bb50a2cd0c 


Sample Query Response (TxnExistsz2) 

TxnExists-2&QueryDesc-Invalid Service 
ID&TransactionType-QUERY&PymtMethod-CC&ServicelD-TI1&PaymentlD-JEFSIT 131107000 
03&OrderNumber-&Amountz0.14&CurrencyCode-MYR&TxnID-&IssuingBank-&TxnStatus-- 
2&AuthCode-&BankRefNo-&TxnMessage-&HashValue-9ee16092009244441924993361 al 38be 
3da59d8545db1 4e5985f787e1 254c4c7 
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Capture Request (Merchant System — Payment Gateway) 


The following fields are the Payment information expected from Merchant System to Payment 
Gateway in order to capture the original authorization transaction (payment request with 
transaction type AUTH): 


: Data Max X 
9 

No. Field Type | Length Req? Description 

1. | TransactionType A 7 Y CAPTURE 
Payment Method submitted in the original 

2. ЕО n ч ы Payment Request being captured 

3. | ServicelD AN 3 Y Merchant Service ID given by eGHL 
Unique Transaction ID or Reference 

4. PaymentID AN 20 Y Code assigned by Merchant System for 
the original authorization transaction 
Transaction amount to be captured in 2 
decimal places, e.g. 100.00 

5. | Amount N 12(2) Y 
Should not be exceeding the original 
authorization request amount 
Original ^ authorization ^ transaction's 

б. Оше прус вар N 3 x 1504217 3-letter currency code 
Message digest value calculated by 
Merchant System in hexadecimal string 

7. | HashValue AN 40 Y using SHA256 hash algorithm 


Re: Section 2.11.1.3 
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Capture Response (Merchant System — Payment Gateway) 


Upon capture process completion, the following fields will be returned from Payment Gateway to 
Merchant System in order to complete an end-to-end capture process. 


No MerchantReturnURL involved. Merchant System can get Capture response on the same 


session. 
: Data Max E 
9 
No. Field Type | Length Req? Description 
1. | TransactionType A 7 Y Follows request 
2. PymtMethod A 3 Y Follows request 
3. ServicelD AN 3 Y Follows request 
4. PaymentID AN 20 Y Follows request 
5. | Amount N 12(2) Y Follows request 
6. | CurrencyCode N 3 Y Follows request 
Capture status 
7. | TxnStatus N 4 Y 
Re: Section 3.2 
Message digest value calculated by 
Payment Gateway in hexadecimal string 
8. | HashValue AN 100 Y using SHA256 hash algorithm 
Re: Section 2.11.1.2 
9. | TxnMessage AN 255 N Message that briefly ^ explains the 
response 
Unique Transaction ID or Reference 
Code assigned by Payment Gateway for 
10. | TxnID AN 30 N ће original authorization transaction, 
available only if Payment Gateway 
received the original authorization 
transaction 
This field is the Bank Name keyed in by 
11. | IssuingBank AN 30 N customer оп eGHL Payment Info 
Collection Page 
Available only if Payment Gateway 
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received the original authorization 
transaction 


12. | AuthCode 


AN 


12 


Available only if Payment Gateway 
received the original authorization 
transaction and only if bank returned the 
Auth Code 


Sample Capture Response (A single string will be returned to Merchant System on the 


same Capiure session) 


ServicelD=D01&PymtID=ABC 1234567890&TxnStatus=0& 
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2.7 | Reversal Request (Merchant System — Payment Gateway) 


Prior to sending Reversal, recommended Merchant System to send a Query request to Payment 
Gateway to get the actual payment status. Based on Query response, Merchant System will be 
able to know whether the payment transaction is successful in order to further determining 
whether to send a Reversal request to reverse the original payment. 


Under the following situations, Merchant System can send Reversal request to Payment Gateway 
to reverse payment previously sent to Payment Gateway: 


1. Error Handling 
a. Timeout — Merchant System successfully sent out Payment request to Payment 
Gateway but Merchant System is not able to receive response within timeout 

period. 


b. Others — Any other errors, encountered by Merchant System, that could have 
direct impact to the payment, such as power failure, database errors, hardware 
failure and system failure (bugs, services interrupted). 


2. Product Fulfillment Failure 
Merchant System received payment approved status from Payment Gateway but 
Merchant System somehow failed to complete product fulfillment process for the 
respective booking, reservation or order made by the consumer due to certain scenarios 
such as inventory availability problem or unforeseen price changes problem. 


Some tips for Reversal handling by Merchant System: 
1. Reversal is not allowed to be used by merchants for Refund purposes. 


2. Reversal process can only be performed before bank's settlement. As such, if any of the 
above scenarios occurred, it is advisable to reverse a transaction within one hour of its 
original Sale time. Reversal of a transaction already settled by bank will be rejected with 
TxnStatus=1 (Failed). Merchant System should not attempt Reversal anymore. 


3. Reversal amount must be the same as the original Payment amount. Partial Reversal will 
be rejected with TxnStatus=-1 (Not Found). Merchant System should only attempt 
Reversal with the original Payment amount and currency code. 


4. Merchant System can retry performing Reversal of the respective transaction upon 
receiving Query TxnStatus = 31 or Reversal TxnStatus=2 (Reversal is pending 
processing) or TxnStatus--2 (Internal system error) or when Merchant System 
encountered communication error with Payment Gateway during Reversal processing, 
such as Merchant System failed to send Reversal request or timeout Payment Gateway 
for Reversal response. Under these circumstances, in order to obtain Reversal response, 
Merchant System can either send Query to check whether status received is 
TxnStatus=9 (Transaction Reversed) or perform Reversal request again and each 
Reversal retry attempt is recommended to be at least 5 minutes apart in order to save 
server and network resources. 


5. |f Merchant System somehow failed to receive Payment response from Payment 
Gateway, the original Payment request could be failed or never received by Payment 
Gateway. For such Reversal, Merchant System will receive successful Reversal response 
with TxnStatus=0 (Transaction Reversed). Merchant System should not attempt 
Reversal anymore. 
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The following fields are the Payment information expected from Merchant System to Payment 
Gateway in order to reverse the original sale/payment: 


1 Data Max AER 
9 
No. Field Type | Length Req? Description 


1. | TransactionType A 5 Y RSALE - Reversal 


Payment Method submitted in the original 


= iu n : X Payment Request being reversed 


3. | ServicelD AN 3 Y Merchant Service ID given by eGHL 


Unique Transaction ID or Reference 
4. PaymentID AN 20 Y Code assigned by Merchant System for 
the original Payment transaction 


Original Payment transaction amount to 
be reversed in 2 decimal places, e.g. 
5. | Amount N 12(2) Y 100.00 


No partial reversal is allowed 


Original Payment transaction’s 1504217 


n CurrencyCode N 3 Y 3-letter currency code 
Message digest value calculated by 
Merchant System in hexadecimal string 
7. | HashValue AN 40 Y using SHA256 hash algorithm 


Re: Section 2.11.1.3 
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Sample VB.net Code HTTP POST Reversal Request And Receive Reversal Response 
Reference: http://msdn.microsoft.com/en-us/library/debx8sh9.aspx 


Imports System 
Imports System.IO 
Imports System.Net 
Imports System.Text 
Namespace Examples.System.Net 
Public Class WebRequestPostExample 


Public Shared Sub Main() 
' Create a request using a URL that can receive a post. 
Dim request As WebRequest - WebRequest.Create("https://secure2pay.e- 
ghl.com/IPG/payment.aspx ") 
' Set the Method property of the request to POST. 
request.Method - "POST" 
' Create POST data and convert it to a byte array. 


Dim postData As String - 
"TransactionType-RSALE&PymtMethodzCC&ServiceID-A07&PaymentID- 
ABCDEFGH130820142128&Amount-228.00&CurrencyCode-MYR&HashValue-hash value generated" 


Dim byteArray As Byte() - Encoding.UTF8.GetBytes(postData) 
' Set the ContentType property of the WebRequest. 
request.ContentType = "application/x-www-form-urlencoded" 
' Set the ContentLength property of the WebRequest. 
request.ContentLength - byteArray.Length 

' Get the request stream. 

Dim dataStream As Stream - request.GetRequestStream() 

' Write the data to the request stream. 
dataStream.Write(byteArray, 0, byteArray.Length) 

' Close the Stream object. 

dataStream.Close() 

' Get the response. 

Dim response As WebResponse - request.GetResponse() 

' Display the status. 

Console.WriteLine(CType(response, HttpWebResponse).StatusDescription) 
' Get the stream containing content returned by the server. 
dataStream - response.GetResponseStream() 

' Open the stream using a StreamReader for easy access. 

Dim reader As New StreamReader(dataStream) 

' Read the content. 

Dim responseFromServer As String - reader.ReadToEnd() 

' Display the content. 

Console.WriteLine(responseFromServer) 


' +++++ Parse Reversal Response Here +++++++++++++++++++++++++++++++++++++ 

' +++++ Sample of Reversal Response Is Available On The Next Section +++++ 

' Clean up the streams. 
reader.Close() 
dataStream.Close() 
response.Close() 

End Sub 
End Class 
End Namespace 
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Reversal Response (Payment Gateway — Merchant System) 


Upon reversal process completion, the following fields will be returned from Payment Gateway to 
Merchant System in order to complete an end-to-end payment reversal process. 


No MerchantReturnURL involved. Merchant System can get Reversal response on the same 


session. 
: Data Max E 
9 
No. Field Type | Length Req? Description 
1. | TransactionType A 5 Y Follows request 
Payment Method 
2. | PymtMethod A 3 Y CC - Credit Card 
DD - Direct Debit 
WA - e-Wallet 
3. ServicelD AN 3 Y Follows request 
4. PaymentID AN 20 Y Follows request 
5. | Amount N 12(2) Y Follows request 
6. | CurrencyCode N 3 Y Follows request 
Reversal status 
7. | TxnStatus N 4 Y 
Re: Section 3.4 
Message digest value calculated by 
Payment Gateway in hexadecimal string 
Se y nsnvelue AN | 109 Y | using SHA256 hash algorithm 
Re: Section 2.11.1.2 
9. | TxnMessage AN 255 N Message that briefly explains the 
response 
Unique Transaction ID or Reference 
Code assigned by Payment Gateway for 
10. | TxnID AN 30 N the original Payment transaction, 
available only if Payment Gateway 
received the original Payment transaction 
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11. 


IssuingBank 


AN 


30 


For PymtMethod “СС”, this field is the 
Bank Name keyed in by customer on 
eGHL Payment Info Collection Page 


For PymtMethod “ОР”, this field is the 
Bank Name chosen by customer to 
perform Direct Debit transaction 


Available only if Payment Gateway 
received the original Payment transaction 


12. 


AuthCode 


AN 


Available only if Payment Gateway 
received the original Payment transaction 
and only if bank returned the Auth Code 


Sample Reversal Response (A single string will be returned to Merchant System on the 


same Reversal session) 
ServicelD=D01&PymtID=ABC1234567890&TxnStatus=0& 
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2.9 Refund Request (Merchant System — Payment Gateway) 


The following fields are the Payment information expected from Merchant System to Payment 
Gateway in order to refund the original sale/payment: 


: Data Max EM 
9 
No. Field Type | Length Req? Description 


1. | TransactionType A 5 Y REFUND - Refund 


Payment Method submitted in the original 


2. аа А : x Payment Request being refunded 


3. | ServicelD AN 3 Y Merchant Service ID given by eGHL 


Unique Transaction ID or Reference 
4. PaymentID AN 20 Y Code assigned by Merchant System for 
the original Payment transaction 


Transaction amount to be refunded in 2 
decimal places, e.g. 100.00 


5. | Amount N 12(2) Y 
Should not be exceeding the original sale 
request amount 
6. | CurrencyCode N 3 Y Original Payment transaction's 1504217 
3-letter currency code 
Message digest value calculated by 
Merchant System in hexadecimal string 
7. | HashValue AN 40 Y using SHA256 hash algorithm 


Re: Section 2.11.1.3 
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2.10 Refund Response (Payment Gateway — Merchant System) 


Upon refund process completion, the following fields will be returned from Payment Gateway to 
Merchant System in order to complete an end-to-end refund process. 


No MerchantReturnURL involved. Merchant System can get Refund response on the same 


session. 
: Data Max US 
9 

No. Field Type | Length Req? Description 

1. | TransactionType A 7 Y Follows request 

2. PymtMethod A 3 Y Follows request 

3. ServicelD AN 3 Y Follows request 

4. PaymentID AN 20 Y Follows request 

5. | Amount N 12(2) Y Follows request 

6. | CurrencyCode N 3 Y Follows request 
Capture status 

7. | TxnStatus N 4 Y 
Re: Section 3.4 
Message digest value calculated by 
Payment Gateway in hexadecimal string 

8. | HashValue AN 100 Y using SHA256 hash algorithm 
Re: Section 2.11.1.2 

9. | TxnMessage AN 255 N Message that briefly ^ explains the 
response 
Unique Transaction ID or Reference 
Code assigned by Payment Gateway for 

10. | TxnID AN 30 N the original Payment transaction, 
available only if Payment Gateway 
received the original Payment transaction 
This field is the Bank Name keyed in by 
customer on еони Payment Info 

11. | IssuingBank AN 30 N Collection Page 
Available only if Payment Gateway 
received the original Payment transaction 
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12. 


AuthCode 


AN 


12 


Available only if Payment Gateway 
received the original Payment transaction 
and only if bank returned the Auth Code 


Sample Refund Response (A single string will be returned to Merchant System on the 


same Refund session) 
ServicelDzD01&PymtlD-ABC1234567890& TxnStatus-0& 
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2.11 Additional Information 


2.11.1 Usage of Hash Value 


A hash value (or simply hash), also called a message digest, is a number generated from a 
text string. The hash is substantially smaller than the text string itself, and is generated by a 
formula or hash algorithm in such a way that it is extremely unlikely that some other texts will 
produce the same hash value. 


For online payment processing, hashing plays an important role to ensure the transmitted 
request and response messages have not been tampered with, in order to achieve data 
integrity. 


For transaction request, Merchant System is required to use SHA256 hash algorithm to 
generate a hash value from a combination of Merchant Password and certain transaction 
fields, and then includes the hash value in HashValue field before sending the request to 
Payment Gateway which will then generate a hash value based on the same method and then 
verify these two hash values. If both hash value matched, Payment Gateway will further 
process the payment request or else it will discard the request message and will treat it as an 
invalid message. 


Likewise, for transaction response, Merchant System can generate hash value based on 
Merchant Password and certain response fields and then verify this hash value with the value 
retrieved from HashValue field of response. If both hash value mismatched, Merchant System 
can treat the response as invalid and discard it. Merchant System can only accept genuine 
payment response which had not been tampered with. 


2.11.1.1 Payment Request Hashing 


Payment request's Hash Value should be generated based on the following fields: 


Hash Key = Password + ServicelD + PaymentlD + MerchantReturnURL + 
MerchantApprovalURL + MerchantUnApprovalURL + MerchantCallBackURL + Amount 
+ CurrencyCode + CustlP + PageTimeout + CardNo + Token 


Hash Key Example 
abc123S22PAYTEST 123https://www.shop.com/success.asp12.34MYR113.210.6.1509004 
444333322221111 


Hash Value (SHA256) 


280100720 7bdbdb6e8ae3890Fdb56c541c552c10b609b978Fd69428 fbb 
Ta4fbc2 


2.11.1.2 Payment/Query/Reversal/Capture/Refund Response Hashing 


Payment/Query/Reversal/Capture/Refund response’s Hash Value should be generated based 
on the following fields: 


Hash Key = Password + TxnID + ServicelD + PaymentlD + TxnStatus 
+ Amount + CurrencyCode + AuthCode 
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Hash Key Example 
abc123TESTTXN123522PAYTEST123112.34458123456 


Hash Value (SHA256) 
94f47e73f659b8a44bac8d8a1274fc884d1fb 75D 7c3d0de47p1439378c8 
ce02cf 

2.11.1.3 Query/Reversal/Capture/Refund Request Hashing 


Query/Reversal/Capture/Refund request's Hash Value should be generated based on the 
following fields: 


Hash Key = Password + ServicelD + Раутепіїр + Amount + CurrencyCode 


Hash Key Example 
abc123S22PAYTEST12312.34MYR 


Hash Value (SHA256) 
320b0e212a875228£580ef£d87604534a£47055e56167aa7e83842c£6878 


8097b5 
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3.1 Transaction Type 


TransactionType Description 
SALE Payment transaction 

AUTH Authorization transaction 
CAPTURE Capture transaction 

QUERY Status inquiry transaction 
RSALE Reversal transaction 

REFUND Refund transaction 


3.20  Payment/Capture Transaction Status 


TxnStatus Description 
0 Transaction successful 
1 Transaction failed 


3.3 Query Transaction Status 


GHL ePayments 


TxnStatus Description 
0 Transaction successful (for transaction type SALE) 
1 Transaction failed 
2 Sale pending, retry Query 
10 Transaction refunded 
15 Transaction authorized (for transaction type AUTH) 
16 Transaction captured 
Reversal pending, merchant system can retry Reversal if merchant system 
31 initiated the Reversal request or else merchant system can retry Query 
9 Transaction reversed 
-1 Transaction not exists/not found 
-2 Internal system error 
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3.4  Reversal/Refund Transaction Status 


TxnStatus Description 


0 Reversal/Refund success 


Reversal/Refund failed, original transaction could be still under processing or 
failed due to other reasons like rejected by bank; Merchant System can send 
4 a Query to get actual payment status. If payment status from Query 
response is transaction successful, then only determine to whether proceed 
with sending Reversal/Refund. This will minimize the possibility of 
Reversal/Refund failed due to original transaction still under processing 


2 Reversal/Refund pending, merchant system can retry Reversal/Refund 


Original transaction not found based on ServicelD, PaymentID, Amount and 
CurrencyCode, merchant system can stop Reversal/Refund 


Internal system error encountered during Reversal/Refund processing, 
Merchant System can retry Reversal/Refund 


3.5 Currency Code 


Currency Code Currency 
MYR Malaysia Ringgit 
SGD Singapore Dollar 
THB Thai Baht 
CNY China Yuan (Ren Min Bi) 
PHP Philippine Peso 


3.6 Language Code 


Language Code Language 
EN English (default language) 
BM Malaysia 
TH Thai 
CN Chinese 


3.7 Country Code 


Country Code Country 


Indonesia 
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